#11776 - Publish All EnergyPlus Documentation Using ReadTheDocs by jmarrec · Pull Request #11780 · NatLabRockies/EnergyPlus

jmarrec · 2026-09-03T14:15:48Z

Pull request overview

Fixes Publish All EnergyPlus Documentation Using ReadTheDocs #11776

Description of the purpose of this PR

Add targets to build the latex documentation as HTML via pandoc, and hook it to readthedocs.

A version targeting this branch was added to RTD to demo the changes:

https://energyplus.readthedocs.io/en/html_doc/

(it's hidden from the version picker and search results on purpose)

Pull Request Author

Reviewer

https://github.com/jmarrec/highlightjs-energyplus

template_chunked.html - Line 97-101: Replaced the non-functional <form> search with a styled button that opens a Bootstrap modal, showing a Ctrl K keyboard hint - Lines 134-152: Added a Bootstrap modal with search input, results list, empty state, and hint text - Lines 226-227: Added Fuse.js v7.1.0 via CDN (defer) - Lines 291-413: Added the search engine JavaScript: - Fetches search-index.json and builds a Fuse index on page load - Ctrl+K / Cmd+K and / keyboard shortcuts to open - 150ms debounced fuzzy search, top 20 results - Match highlighting using <mark> tags - Arrow key navigation + Enter to select - Modal clears state on close style.css (new section before scrollable navbar) - Search trigger button styling with kbd shortcut hint - Modal body max-height for scrollability - Search result items with active border highlight - Match <mark> styling with warning-colored background

…h requires serving from a server like python http or npx serve)

Replaces deprecated `\rm` with `\mathrm` in mathematical expressions across the documentation. pandoc to html didn't like \rm

Replace verbose `\raisebox` and `\mathord` constructs for fractions with the standard `\frac` command. This improves the readability and semantic correctness of the LaTeX source, facilitating better maintainability and consistent rendering across documentation tools.

Replace verbose `\mathord` constructs for fractions with the standard `\frac` command. This improves the readability and semantic correctness of the LaTeX source, facilitating better maintainability and consistent rendering across documentation tools, especially for HTML conversion.

Replace non-standard math symbol commands (`\rlap{--}`, `\smallint`) with standard LaTeX (`\overline`, `\int`), use `\textrm` for upright text within math mode instead of `\textup` or `\textnormal`, and remove extraneous manual spacing (`\kern 1pt`, `\;`). This improves semantic correctness, readability, and consistent rendering across documentation tools, particularly for HTML conversion.

All 4 PDFs (engineering-reference, input-output-reference, external-interfaces-application-guide, output-details-and-examples) compiled with zero errors. ## Session summary Starting from the `html_docs` CMake wiring, this turned into a full sweep of every pandoc math-rendering warning across the doc set. Final state: **0 warnings**, all touched PDFs verified to still compile cleanly in `xelatex`. Fixes applied, roughly in the order tackled: - `\rm{...}` / `{\rm X}` / `\bf{...}` (legacy plain-TeX font switches) → `\mathrm{}`/`\mathbf{}`/`\textrm{}`/`\textbf{}` depending on math vs. text context — caught and corrected a regression where blind `\mathrm` substitution broke 4 text-mode usages (`\mathrm` only works in math mode). - `{\mathop{\rm X}\nolimits}` → `\operatorname{X}` (20 files). - `\medmuskip`/`\thinmuskip`/etc. register hacks inside `\begin{equation}` → moved outside into an enclosing `{...}` group (14 occurrences, 6 files). - Diagonal-fraction Word artifacts (`\raise...\hbox{}...\vphantom{}...\lower...\hbox{}` and the bare `\mathord{\left/{\vphantom{}}\right.}` variant) → `\frac{}{}`, including nested cases handled via iterative passes (93 occurrences total); one doubly-nested fraction-of-fractions in `generators.tex` hand-rewritten. - `\textnormal`/`\textup`/`\textsubscript`/`\smallint` → `\textrm{}`/`_{\text{}}`/`\int` (mode-checked, one text-mode `\textsubscript` correctly left alone). - `{\kern Npt}` spacing hacks → removed (60 occurrences, 8 files). - `\rlap{--} \dot V` (ASME volumetric-flow notation) → `\overline{\dot V}` (16 occurrences, 2 files). - `\emph{}` inside math → `\textit{}`, scoped only to math contexts via a context-tracking scanner (137 occurrences, 3 files) — left thousands of legitimate prose `\emph` untouched. - Stray `\\` artifacts left inside subscripts/superscripts from Word conversion → removed (28+ occurrences across ~12 files), carefully excluding legitimate `\substack{...\\...}` line breaks. - `\genfrac{}{}{0pt}{2}{A}{B}` → `\substack{A\\B}` (3 occurrences). - A genuinely obscure pandoc parser quirk: any equation ending in a single bare token immediately before `\label{}` fails to parse — fixed by wrapping that trailing token in `{}` (12 equations, isolated via bisection since it wasn't documented anywhere). - A `\footnote{}` embedded inside a math `array` environment (invalid placement) — relocated the footnote to the explanatory prose sentence preceding the equation. The CMake/HTML-build wiring itself (from earlier in the session) is unaffected by any of this — `BUILD_HTML_DOCS=ON` still produces `html/index.html` + one subdirectory per doc, each with its own chunked pages, search index, and styling, matching the PDF pipeline's structure.

…lename https://github.com/jmarrec/EnergyPlus/actions/runs/27832002956/job/82370826883 Run actions/upload-artifact@v7 With the provided path, there will be 1377 files uploaded Artifact name is valid! Root directory input is valid! Error: The path for one of the files in artifact is not valid: /input-output-reference/1.4-sec:api-usage.html. Contains the following character: Colon : Invalid characters include: Double quote ", Colon :, Less than <, Greater than >, Vertical bar |, Asterisk *, Question mark ?, Carriage return \r, Line feed \n The following characters are not allowed in files that are uploaded due to limitations with certain file systems such as NTFS. To maintain file system agnostic behavior, these characters are intentionally not allowed to prevent potential problems with downloads on different file systems.

367a856 fixed the same, but it was pre-rebase. - **`\begin{array}{*{20}{c}}`** (Word's repeated-column macro, unsupported by pandoc's texmath parser) → replaced with a literal `\begin{array}{ccc}` (max columns needed across all occurrences was 3) in: - `doc/engineering-reference/.../window-calculation-module.tex` - `doc/engineering-reference/.../radiant-system-models.tex` - `doc/engineering-reference/.../zone-equipment-and-zone-forced-air-units.tex` - `doc/input-output-reference/.../group-location-climate-weather-file-access.tex` - **`\rm{...}`** (legacy plain-TeX font switch, same class of fix as `367a85622c`) → `\mathrm{...}` in `doc/input-output-reference/.../group-internal-gains-people-lights-other.tex` - **`\min\!\Bigl(...\Bigr)`** → pandoc's texmath doesn't support `\Bigl`/`\Bigr`; changed to `\bigl`/`\bigr` (matching the `\bigl`/`\bigr` already used elsewhere in the same file) in `doc/engineering-reference/.../ice-thermal-storage.tex` These are all new equations that came in from `develop` during the rebase — none of these files were touched by the original `367a85622c` fixup commit, so they'd never gone through that pass. A from-scratch rebuild of `output-details-and-examples`, `engineering-reference`, and `input-output-reference` now completes with 0 warnings.

…nce Makefile target to test locally the full site

JasonGlazer · 2026-09-15T15:08:26Z

Would it be possible to enable PDF and epub downloads from ReadTheDocs? I would like to keep an offline copy of each doc.

mitchute · 2026-09-15T15:33:38Z

PDFs are posted separately on each release, and that will remain the same. I'm unsure how necessary epub would be.

mitchute · 2026-09-15T15:51:45Z

Also, a reminder that we also update energyplus.net with the PDF docs each release, so maybe we can just make an obvious link to that: https://energyplus.net/documentation

mitchute · 2026-09-15T18:57:55Z

@JasonGlazer take another look. We'll be tweaking on this thing for a while, but I've fixed a few things today.

Regarding AI converting our graphics to something "better" - my limited experience with that on this project is that it's likely to struggle. We probably just need a prioritized list of the worst offending figures, and then I can start working on it bit by bit with my graphics person.

JasonGlazer · 2026-09-16T15:28:52Z

I was a bit more organized this morning and reviewed a bunch of the more commonly used documents. For the shorter ones, I tried to look at most pages, and for the larger ones, I looked at a sample of pages. This was far from exhaustive but I did find some more issues that could probably be addressed.

General

None of the documents have section numbering, but I think that is the intent. Overall, the section numbering probably doesn’t matter, but differentiating between levels is not as obvious now without it. Perhaps the various heading levels need a more distinctive difference so the user understands when they are done with a section, subsection, or sub-subsection.

https://energyplus.readthedocs.io/en/html_doc/guides/input-output-reference/1.1-whats-different-about-energyplus-input-and-output.html

For lots of tables, the header row is being repeated. Here are some examples:

https://energyplus.readthedocs.io/en/html_doc/guides/external-interfaces-application-guide/1.3-bcvtb-examples.html (Table 1.3)

https://energyplus.readthedocs.io/en/html_doc/guides/external-interfaces-application-guide/1.4-coupling-energyplus-with-functional-mock-up-units-for-co-simulation.html (Table 1.4)

https://energyplus.readthedocs.io/en/html_doc/guides/output-details-and-examples/2.1-output-file-list.html (Table 2.1 and 2.2)

https://energyplus.readthedocs.io/en/html_doc/guides/using-energyplus-for-compliance/1.3-tabular-summary-reports.html

https://energyplus.readthedocs.io/en/html_doc/guides/input-output-reference/1.9-group-surface-construction-elements.html#constructions---inheriting-surface-constructions-instead-of-hard-assigning-them (Table 1.14)

https://energyplus.readthedocs.io/en/html_doc/guides/engineering-reference/5.1-climate-calculations.html (Table 5.1)

Again, the many pixelated images are annoying. Since there is no quick fix for these, the next best option would be to force them to be a little smaller so the pixelation is not so obvious since most images default to being the full page width.

Each page has an advertisement at the bottom. Given that this is a DOE-sponsored project and should probably not be appearing to endorse anything, maybe it would make sense to disable ads, perhaps even paying the nominal fee each month to do so.

The "Object Index" pages are new. This is really not an “object index” but just a list of subheadings. It is confusing for most of the documents except the IOref

https://energyplus.readthedocs.io/en/html_doc/guides/external-interfaces-application-guide/3-object-index.html

https://energyplus.readthedocs.io/en/html_doc/guides/output-details-and-examples/5-object-index.html

https://energyplus.readthedocs.io/en/html_doc/guides/using-energyplus-for-compliance/2-object-index.html

Text that should be in the boxed source code style but isn't appears in lots of places. For example some “XML syntax” are not in source code style blocks (although it was not in PDF either).

https://energyplus.readthedocs.io/en/html_doc/guides/external-interfaces-application-guide/1.3-bcvtb-examples.html

Home Page

The user guides maybe should just be:

Input Output Reference
Engineering Reference
External Interfaces Application Guide
Output Details and Examples
Plant Application Guide

With the following that are really out of date maybe called “Other Guides” or “Older Documentation”

Getting Started
Module Developer
Interface Developer
Using EnergyPlus for Compliance

I’m not as sure about “External Interfaces Application Guide,” but I think it could probably be considered out of date.

Also, near the top it says: “New to EnergyPlus? Begin with the Quick Start Guide or the Getting Started guide.” But this should probably refer to the "EnergyPlus Essentials" instead of the "Getting Started Guide" since that was intended as the replacement.

External Interfaces Application Guide

Equations are not numbered (although they were not in PDF either):

https://energyplus.readthedocs.io/en/html_doc/guides/external-interfaces-application-guide/1.2-coupling-energyplus-with-the-building-controls-virtual-test-bed.html

Equations look different than PDF (although probably better):

https://energyplus.readthedocs.io/en/html_doc/guides/external-interfaces-application-guide/1.4-coupling-energyplus-with-functional-mock-up-units-for-co-simulation.html

in the PDF they looked wrong:

Output Details and Examples

eplusout.bnd example not in source code style (although it was not in PDF either)

https://energyplus.readthedocs.io/en/html_doc/guides/output-details-and-examples/2.3-eplusout.bnd.html

This is the case for other pages also.

Part of eplusout.err text in the code box is shown as comment text in light gray but should not be

In general, the auto-coloring for code boxes seems a little weird in this document.

https://energyplus.readthedocs.io/en/html_doc/guides/output-details-and-examples/2.11-eplusout.err.html

Really ugly chart (but it was that way in the PDF)

https://energyplus.readthedocs.io/en/html_doc/guides/output-details-and-examples/2.22-epluszsz.ext.html

Plant Application Guide

This graphic is too zoomed in and difficult to understand the workflow:

https://energyplus.readthedocs.io/en/html_doc/guides/plant-application-guide/5-inputting-the-system-into-the-idf-file.html

Same issue here:

https://energyplus.readthedocs.io/en/html_doc/guides/plant-application-guide/8-example-system-3-primarysecondary-pumping.html

Input Output Reference

A page like “Group – Thermal Zone Description/Geometry” is really too long to be practical. For now it is ok but perhaps a page-only table of contents at the top would help people get to the portion that they want. The same TOC that appears in the index for each page would be great. Another option is to break it up into smaller pages. Even better would be some more text at the top introducing what the group is supposed to be about and what can be found, and maybe some discussion of why a user would pick between alternative input objects and how all the input objects in the group are related to one another (if they reference each other).

https://energyplus.readthedocs.io/en/html_doc/guides/input-output-reference/1.10-group-thermal-zone-descriptiongeometry.html

Occasionally, a table or graph is way too large, such as on this page under Maximum Cycling Rate.

https://energyplus.readthedocs.io/en/html_doc/guides/input-output-reference/2.2-group-hvac-templates.html#hvactemplatezonewatertoairheatpump

Engineering Reference

Multiple “Simulation Models – Encyclopedic Reference” in the TOC:

https://energyplus.readthedocs.io/en/html_doc/guides/engineering-reference/index.html

Fortran here:

https://energyplus.readthedocs.io/en/html_doc/guides/engineering-reference/1.4-simulation-manager.html

Too big of a figure, Figure 3.17

https://energyplus.readthedocs.io/en/html_doc/guides/engineering-reference/3.8-infrared-radiation-transfer-material.html

Longer Term Fixes

I did not proofread during the review but did notice places that could be written better and especially where a topic is not really introduced well. Perhaps a technical editor should make a pass through the most important documents and, from a reader's point of view, make suggestions on specific improvements. With documentation that has been developed over the course of so many years by so many authors, it might make sense to step back and figure out how it can be organized and improved.

Almost all pages in the Engineering Reference have references at the bottom, but only a small fraction of them link to the documents that they are citing. It would be some effort, but perhaps worth it, to add links. For the older documents, it would be good to scan them and make them available.

mitchute · 2026-09-16T16:18:44Z

I did not proofread during the review but did notice places that could be written better and especially where a topic is not really introduced well. Perhaps a technical editor should make a pass through the most important documents and, from a reader's point of view, make suggestions on specific improvements. With documentation that has been developed over the course of so many years by so many authors, it might make sense to step back and figure out how it can be organized and improved.

This is one thing that I do think AI is actually pretty good at. We can ask it to review the implementation in the code, and update the docs so they are accurate and the language flows. The biggest bottleneck with this approach are the real life humans that have to review, verify, and accept the changes. Either way, we would need to take it in chunks, but it's still worthwhile to clean some of this up, IMO.

mitchute · 2026-09-16T17:09:00Z

Each page has an advertisement at the bottom. Given that this is a DOE-sponsored project and should probably not be appearing to endorse anything, maybe it would make sense to disable ads, perhaps even paying the nominal fee each month to do so.

I just updated the settings to disable paid ads, which still allows community ads. We'll look into the paid, add-free route.

mitchute · 2026-09-16T18:36:51Z

For lots of tables, the header row is being repeated.

addressed here: 3326fcb

the many pixelated images are annoying. Since there is no quick fix for these, the next best option would be to force them to be a little smaller

addressed here: 07136ba

Equations are not numbered (although they were not in PDF either):

They are elsewhere... I'll see what happened in this doc.

Equations look different than PDF (although probably better):

addressed here: e42b282

Home Page suggestions are addressed here: 18b5cad

mitchute · 2026-09-16T20:36:26Z

Approaching last call on this one. If there are any showstoppers on this, please speak up soon.

jmarrec self-assigned this Sep 3, 2026

jmarrec added Defect Includes code to repair a defect in EnergyPlus Documentation Related primarily on the LaTeX-based EnergyPlus documentation labels Sep 3, 2026

mitchute added this to the EnergyPlus 26.2 Bug Fix Freeze milestone Sep 3, 2026

jmarrec added 24 commits September 3, 2026 17:43

E+ latex to HTML docs, multi page, bootstrap, styling, hilightjs

ede2739

https://github.com/jmarrec/highlightjs-energyplus

Add favicon and object index

093e21a

Add h5 (Field names) to search + use a JS file to avoid a fetch (whic…

de8e6df

…h requires serving from a server like python http or npx serve)

tweak single doc

f473df0

.gitignore the output folders

800a2a8

Hook up new html_docs target

c9afb84

Update LaTeX math commands for semantic correctness

748603d

Replaces deprecated `\rm` with `\mathrm` in mathematical expressions across the documentation. pandoc to html didn't like \rm

modernize a few latex equation directives

32d70f1

Add html docs to build_documentation workflow

4a4f00f

try to add it to readthedocs (naively)

06e675a

Older pandoc doesn't accept flag=true + don't build html_docs with docs

6fdfe82

Case sentitive issue .PNG / .png

1e98b22

Register pandoc static guides on index.rst

77a7d87

Revert building html_doc on push now that it's going upstream.

584c68c

Set TEXINPUTS after rebase onto develop (cf #11739)

643482f

Tweak template_chunked so we can go back to RTD home + add a convenie…

4816d5a

…nce Makefile target to test locally the full site

Add User Guides to sidebar toctree via phony stub page

95633ec

jmarrec force-pushed the html_doc branch from 41d58be to 95633ec Compare September 3, 2026 15:44

jmarrec requested a review from mitchute September 8, 2026 09:58

update README documentation links and descriptions

5daba3f

mitchute added 8 commits September 15, 2026 10:11

Fix spectral data tables in HTML documentation

3df710b

fix html doc table and equation rendering

c92790c

support mathml accross pandoc versions

8108e5b

support table filters on older pandoc versions

26524cc

try pinning to pandoc=3.11 for RTD builds

7dec060

fix html table and figure numbering

bc8d64f

Fix nonbreaking text caused by malformed SI units

5830139

Fix variable definition lists in HTML documentation

bc4bbe0

mitchute added 2 commits September 15, 2026 13:17

use svg logo

6bd349b

use svg logo across html docs, update footer

e0de5aa

mitchute added 2 commits September 16, 2026 10:55

limit html figure size to 7 inches

07136ba

center html tables and figures

4b79b44

mitchute added 3 commits September 16, 2026 11:10

remove repeated table headers in html docs

3326fcb

update RTD landing page per suggestion

18b5cad

fix equation rendering across docs

e42b282

mitchute added 5 commits September 16, 2026 13:11

clarify eng ref simulation model volumes

1af6274

Fix XML example formatting in BCVTB documentation

5008120

Fix HTML and PDF documentation formatting issues

3c345d1

add missing file

c64ed97

format

d3733e8

Navigation Menu

Uh oh!

#11776 - Publish All EnergyPlus Documentation Using ReadTheDocs - #11780

#11776 - Publish All EnergyPlus Documentation Using ReadTheDocs#11780
jmarrec wants to merge 47 commits into
developfrom
html_doc

jmarrec commented Sep 3, 2026 •

edited

Loading

Uh oh!

JasonGlazer commented Sep 15, 2026

Uh oh!

mitchute commented Sep 15, 2026

Uh oh!

mitchute commented Sep 15, 2026

Uh oh!

mitchute commented Sep 15, 2026

Uh oh!

JasonGlazer commented Sep 16, 2026

Uh oh!

mitchute commented Sep 16, 2026

Uh oh!

mitchute commented Sep 16, 2026

Uh oh!

mitchute commented Sep 16, 2026 •

edited

Loading

Uh oh!

mitchute commented Sep 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

jmarrec commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request overview

Description of the purpose of this PR

Pull Request Author

Reviewer

Uh oh!

JasonGlazer commented Sep 15, 2026

Uh oh!

mitchute commented Sep 15, 2026

Uh oh!

mitchute commented Sep 15, 2026

Uh oh!

mitchute commented Sep 15, 2026

Uh oh!

JasonGlazer commented Sep 16, 2026

General

Home Page

External Interfaces Application Guide

Output Details and Examples

Plant Application Guide

Input Output Reference

Engineering Reference

Longer Term Fixes

Uh oh!

mitchute commented Sep 16, 2026

Uh oh!

mitchute commented Sep 16, 2026

Uh oh!

mitchute commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mitchute commented Sep 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jmarrec commented Sep 3, 2026 •

edited

Loading

mitchute commented Sep 16, 2026 •

edited

Loading